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Throughout this manual, referencea are made to 
file* (such aa EDWRHST.ASM). These file* may b 
on the supplied diskette (Chapter 9 contains a 
then). This manual is designed to be u 
conjunction with these annotated source tHeo 
•uggested that the reader first list these ti 
refer to them as necessary when reading this 
Assembled list files of Apple r es ident pr o gr 
opposed to printouts of the source files; 
obtained via the supplied 6502 cross assenbl 
Chapter 6). The APPLI-CARD resident programs 
assembled with the standard CP/M assembler 
MAC) . 
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CHAPTER 1/ BIOS lEFORMATIOn 



CP/M consists of 3 sections: 



si -"? " S 



s • 



Console Coamand Proces sor(CCP) 
.„- .. . Basic Disk Operating Systctn (BDOS) 

.'^ . Basic Input Output System (BIOSJ 

ir Of these modules, only the BIOS is hardware dependent 
The APPLI-CARD BIOS uses the Apple ceoputer as its i/o 
processor and sends connands over a cooicunicat ion port 
to direct the Apple. 

The BIOS is hardware dependent code written in assembly 
language. This code translates calls, by both the BDOS 
and from application programs, to commands for use by 
the Apple. When it is necessary that a program 

communicate vith the Apple. « »^^' °«* ^j^ Vt-ptN"" Apb 
RDVRBST.ASM file may be used. The Apple and APPLI-CARD _ 
communicate over a parallel port. This allows both the 
APPLl-CAiD and the Apple tro r-un at the same time and 
not intrude upon each ethers address space. This also 
allows the APPLI-CA£D BIOS to be relatively small, 
because the direct manipulation of the I/O devices is 
^onc in tlie Apple. 

The BIOS baa been ^rr-ansed to support up to 16 masa 
storage devices «« well as 16 character devices. The 
n&sa at-orage devices may be of multiple densities. 
Theae are referenced as drives A: through P:. With the 
use of the IK^TAXL :pTesr«ai, th«6e ievices are 
. atttOTaatlc*lly alloc**ed cieclt vector space, allocation 
sector «pAce, «&d h««t buffers. The user must ensure 
ihat the flxlTrer is in tic proper format. This format 
i« detailed in the BDE3LKPL.A65 file. The character 
devices m«y be »cc«-s-sed by changin:g The I/O byte to use 
tbe firat five device*; the remaining 11 devices must 
be *cce«aed directly from the application code by using 
the iLDF£BST.AS-H lile^ An example ch*racter device 
driver i« CDEXMPL.A65, Ple*a-e r«fer to it for details 
on how to write * character device driver. 
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CHAPTER 2/ APPLE 1/0 PROCESSOE COMMAHD STIOCTDRE 



2.1 IKTRODUCTIOH 



As mentioned previously, the Apple and the APPLI-CARD 
communicste over a parallel port. The APPLI-CARD sends 
commands to the Apple and the Apple performs the 
commands, then waits for the next command. There are 
256 possible commands which the APPLI-CARD may send to 
the Apple. They are divided into 2 Classes: 

.0 through 127 (general commands) 

X28 through 255 (device specific 
''■''*' commands ) 

Each command is followed by parameters with the number 
of parameters being dependent on the command. The 
parameters are simply sent following the command byte. 
For example, the read data command (1) requires the 
starting address and the number of bytes as parameters. 

The following assembly language program segmenf 
demonstrates this (the subroutines used are in the 
RDWRHST.ASM file): - 



LD C , 1 % < 

CALL VHBYTZ 
LD DE.IOOOH 
CALL WEWORD -wM 
LD DE,123E 

CALL VEWORD 
LD HL,20 0H ** I 
ID DE,123H 
CALL REBYTS 35 



;C - READ DATA COKMAKD 
; AND SEND IT 
;DE - STARTING ADDEESS 
; AND SEND IT 
;DE - NUMBER OF BYTES 

TO RECEIVE 
; AND SEND IT 
;EL - LOCATION TO STORE 
;DE - NUXEER OF BYTES 
f CO READ THEM 



2.2 GENERAL 
COMHANDE 



i' % 4- 



-' f ^ -4 ; 



Ky 



Subxou-tinc« VHBYTZ, ^HWOED, And REBYTS are described 
fully ixx the ilDVRHST.ASM file. Briefly, VEBYTE 
Te^Tite« on^ byte from the APPLI-CARD to the Host 
processor (tlic Applet* WHWORD vrire4i two bytes from 
^h« hostr *ad RHBYTS reads multiple bytes from th^ 
boat« 

Currently^, 8 of the 128 possible general commands are 
supported. These mx^ the first 8 commauds (0 through 
7). The next 8 <9 through 15) are reserved for the 
system and must not be U8e4. The 
are undefined* 



remaining 



commanda 
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« 



The following i. . de.cription of the 8 gener.l 

CDiniaands : ^ 

^'i' Botes: 



t 



• All *2 byte parameters are sent low byte 

followed by high byte. 
. Parameters are listed in the order sent 

to the Apple. ,5 



coHMA.ni) pr>sciriPTion 

' — ^ ^^^^ i^M - .. ■ 

Function: ,. • > 

Illegal command Cdoes nothing;. 

Parameters : 
^ "^ Kone. ''I :-^^f^' , '.^4, ' ,. 

'- . ^ ^ Results: :- ^" •- i. - , ^-^^r. >!v 
^^ ^ ' : * . Hone . . ^; .^x t . ^ - ^ j > ; _ . ._ 

-^ '^; ^ I ^- ^ ?: Function: ^ . 

Read data from the Apple memory^ 
^ ' ^ ^ - t'- ' : Comments : ■ 

» ^^ This command reads data from the Apple 

memory sind returns it to the APPLI- 
CARD . 
^^^ ' Parameters: 

C\ Starting address (2 byte^s) . V^y 

'" '.. Kumbor of bytes C2 bytes). 
^ -' ' iLesults^ 

^ ^ Returns the requested number of bytes to 

the APPLl-CARD. 

f ^ Funttion 



i *r ' 



r% 



Vrite d4it^ to the A.pple -memory. 
Comments: 

^his command writes 4*t-a to the Apple 

*iemory* 
t^r^toeters^ , 

^S^'arting address (2 byt^e^)* 
»ufeber of bytes (2 bytes). 
J)^X^ CThe number of bytes is the value 

^on^e^ 

' ' i'^ -- % 'i ff ti ' ,; ,' / ^ -" ' " 

l?u'nttion: £-...;.-, -i t^lJK" .4 

^ecute a routine. 
I^^mlii'e'nts : 

5:his ^command causes the Apple to send * 
routine At the address passed^ The 
Routine must end with a RXT^ 
5>%Y%^eter6 : 

Stuart ing address (2 bytes). 
tlfefeults: 
iionfe. 
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COKMAHD PESCTIIPTIOH 

4 Function: ^^ 

WArm boot operating system. 
"'^^- -^ Comments: . . 

This routine is used by the warm boot 
i . code. Itshould not be used b y 

'^ :^ ; other programs. 

^ '"^ ^ Parameters: 

None . 
Results: . ■ ^u^ 

The operating system is sent to the 

APPLl-CARD. 

5 Function: 

^ Connect a device driver. 

. -^ - f H - ' ^ ; .A-'^' - Comments : ' ■ ' 

This is used by DLDRVR and at boot 

time by DRIVERS. Device drivers are 

^ ^ ^? 4 6502 programs that exist in CP/M 

: 1 < ' - files in a relocatable format. They 

.^..r ;,-, ',..-, ^^^ y^ad into the APPLI-CARD memory 

^> via the normal CP/H commands and 

then arescnttotheApple where 

f) . they are included in the executing 

softvare. General command 5 is used 

^v-^' to download these drivers from 

APPLI-CARD memo to Apple memory. 
Also refer to the example drivers on 
m-^. r i ^ ^ the structure of a driver. See 

DLDRVR.ASM for details. 
Parameters : 

Load address (2 bytes, • relocatable). 
■ * Lerigth of driver i2 bytes). 

Length of Page (1 hyte). 
Tag field Cl byte^ currently 0). 
Device number (2 bytes (upper byte is 
0)). 
!^ t r *. - Humber of devices (Z bytes (uppex byt^e 

^ i is 0)D. 

^ ^^^ ... iLddxesa of initialize entry point C2 

: -^ ^^ ^ / I >> i byt-es) . 

<:.- rvj A4dre^s of read entry point (2 bytes). 

,i Addresa of write entry points (2 bytes). 

Address of other entxy point (2 bytes). 
uz ^ V' Address of polling entry point (2 bytes). 

Driver code (As indicated by length of 

driver). 
Relocation bit map (None if load address 

is 0, else is length of driver/S). 
Page relocation bit map, (Kone if 
length of page is else is length 
^^w^ of driver/ 8). 
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6 Function: 

Read 1 byte from the Apple wemory. 

Comments : 

This routine reads a byte of data using 
6502 direct addressing, instead of 
6502 indirect addressing used in 
commands land2* 
Parameters : » 

« Address to read (2 bytes). 

Results : J 

Returns one byte of data. 

7 ' " Function : 

Write 1 byte of data to the Apple 

- ^ f ' - '^ - memory. 
^ - ^ Comments : . 

^-^ ^ ' This routine writes a byte of data using 

- t ; ^"\ 6502 direct addressing, instead of 

^- :i 6502 indirect addressing used in 

"* ' " c r c o m m a n d s 1 a n d 2 . 

^ Parameters : 
^ Address to write C2 bytes). ^ 

' ^ Data to write (1 byte). 

^''' 'vi ^ ^ Results : ^^-^ 

- »one. 

8 through Reserved for system use. 
15 

16 throngh Undefined* 

127 V 



;' *- 



DETirZ The 128 devix:e commands a-llx)w direct control of 3^ 

X:0"MMANDS devices, vhich ere defined in the Apple. The 32 devices 

*re divided into t-wt> groupa. Sixteen bloclc devices are 
iis-ed to control mass storag-e devices <sn€h as floppy 
dislca}^ and 16 charexter devic«a (such as the conaole 
and printers). Xach device haa four oommanda: 
IHIT1AXI2E, READ, WRITX, and CTBER. OTHER is used to 
define 256 more commands. The first 16 of these *re 
reserved; the remaining 240 are available for use. 
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The following describes the way the device command 
bytes are encoded: 

Bits and 1: Defines which of the four commands to 
use with the device. ■& 4*^ 



-St - 



^<^ t ' s 



- INITIALIZE 

? rf ^ 1 - EEAD 

.;* ^ 2 - WRITE 

3 - OTHER 

Bits 2 through 5: Define which of the 16 devices to 
use. 

- Device ^ . ^ 

1 ■ Device 1 j 

15 " Device 15 
Bit 6: Defines either Block or Character mode. 

■ Block mode 

Tr^ f ... 1 m Character mode 

^^ .s Bit7: Defines General or Device command. 

--^ .\« ? ^ ■ General command ^ 

1 « Device command 

2 3 1 BLOCK Thissection describes how thefour commands are 

DEVICE interpreted for block devices. See BDEXKPL.A65 for an 

COMMANDS example of a blocJc device driver. 

COMMAHD DESCRrPTIOg 

#* INITIALIZE Tunction: 

Initailire the driver. 
Comments: 
... This command causes a call to the 

INITIALIZE eatry point in the 

3/4. >< . Approi>riate driv^x by the Apple 

, c ^ . ; .^ p r o c e a s o r • 1 1 i s a u t o m a t i c a 1 1 y 

:: . /p. called wh«n the driver is connected 

^^.., ^. ^, (General command 5). 

^ ^ Parameters r 
~ i . ^ f % Hotie. 

' ^ ■' I ;> , ^ . ^ Results: 

*„ 5 4 Error code (1 bytes; if no errors then 

- ^ ^ . error code » 0, else error code <> 
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:t ; 



COMNi^HD 



v.^ 



BEnCSLlFTIOn 



READ 



WRITE 



,*^- 



DTEER 



sector of data. 



:|, % -1$ 



Function: 

Read one 
Coninents: 

This coxnmand causes a call to the READ 
entry point in the appropriate 
drivers by the Apple processor. 
Parameters : 

Sector size (2 bytes). 
Drive number (1 by te ) . 
Track number (2 bytes). 
Sector number (2 bytes). 
Results : 

Sector data (sector siic 
Error code (1 byte, 
then error code ■ 0, 
<> 0). 



bytes). 

If no errors 

else error code 



Function: - - ^- -'f-^^ . - ■■ .. ^ -^ 

Write one sector of data. 
Comments : " _ 

This commands causes a call to the WRITE 
entry point in the a p propriate 
driver by the Apple processor. 
Parameter s : 

Sector size (2 bytes). 

Drive number (1 byte). 

Track number (2 bytes). 

Sector number (2 bytes). 

Sector data (sector axxe bytea)* ^*.e. 
Results: 

Error code <1 byte. If no errors then 

error code • 0, else error code <> 0), 



\^ 



Defines 256 oxTicr cominands to a 
deirice. The first 16 are reserved. 



bloci: 



Function: 

Send disic paramexer command. 

Comments : 

This commtmd is used by the BIOS to 

support multiple tlensity disks. Each 
time m disk is used for the first 
time, this command is sent to log in 
the drive. The driver then 
^etermiiies the type t>f disk and 
sends up the appropriate disk 
|>arameters^ These tables s.t^ usually 
created at assembly time. The ds.ra 
is determined by using tlie file 
DISKDATA.ASM file supplied on the 
disk. 



rj 
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r 



COMltABD 



* > 



PgSCRIPTIQg ,*.,.«.. 

Parsceters : 

Kone . 
Results; 

Sector sire (2 bytes). ,, ^ ^ x 
CP/M records per track C2 bytes;. 
CP/M records per host block (1 byte). 
CP/M records per allocation block li 

byte) . 
Sector mask (1 byte). ' 

Sector shift count (1 byte). ' .- 
CP/M records per track (2 bytes). 
Block shift factor (1 byte). 
Block shift mask (1 byte). 
Disk size - 1 in allocation blocks W 

bytes). 
Directory size - 1 (2 bytes). 
Allocation mask (2 bytes). 
Check size (2 bytes). 
Offset to first CP/M directory track i - 

bytes) . V o ^ 

Translation table (2 bytes should be 0). 

Error code (1 byte if no errors thes 

error code - 0, else error code <> 

0). 



T -c 



Function: 

Format command • , 

Comments : 

Formats the entire block device. 
PAXAmetera : 

Drive number (1 byte). 
Eeiult^: 

Error eode (1 byte, if no errors tbe^ 
error «ode • 0, else error code <> 
0). 



2 throiagb 
14 

15 



ieaexved. 



Functions 

Send nam« of driver. 

Comm^nta t 

Ttia command ia uaed to get the name of 
the driver. Since thia command vas 
added after the initial release of the 
software, not all drivera support this 
command. If you wish to use tHe GETKAME 
subroutine, refex ^o EDWREST.ASM . 

Parameter a : 
Kone. 



K^ 
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COKHAHB 



BESCEIFTIOH 



V_/ 



Results : . 

Length of name (1 byte max value of 15; 

Kame characters (byte length of name). 
Error code (1 byte of 0). 



CHARACTER 

DEVICE 

COKHAKDS 



This section describes hovthe four commands arc 
interpreted for character devices. ^See CDEXMPL.A65 for 
an example of a character device driver. 



COMMA TTP 



INITIALIZE 



READ 



VRITE 



J i^' ft t 



DEScniPTion ^ 

Function: 

Initialize the driver. 
Comment s : 

This command causes a call to the 
INITIALIZE entry point of the 
appropriate driver by the Apple 
processor. It i« automatically 
called when the driver is connected. 
Parameters : 

None • 
Results^ 

- Ko errors, else error in 
initialization* 

Function: 

Read a ^y te . 
Comments z 

This command causes a call to the READ 
entry i)t>iTit of the appropriate 
driver by the Apple processor. 
Parameters : 

None . 
Results : 

Character read (1 hyte). 

Function: 

Write a byr«^ 
Comments : 

This command cauacs a call to tlic 1?RITE 
entry point of the appr-opriate 
driver by the Apple proceaaor* 
Parameters: 

Character to vrite (1 byte^^. 
Results : 

None . 
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COKKABD 
OTHER 



DESCRimOH ,e 4^- 

256 other commandt to « character device 
may be used. 41 

Function: 

Output status. Returns the status of the 
character output routine. 
Parameters : 

Hone . 
Results : 

Status code (1 byte, if ready to send 
then status code <> 0, else status 
code " 0). 

Function: 

Input status. Returns the status of the 
character input routine. 
Parameters : 

Hone . 
Results: 

Status code (1 byte, if character is 
ready then status code <> 0, else 
status code * 0} » 

Function: 

Turns on the video for this device. 
Comments : 

This is used for switching from the 
Apple video to the console video. 
Parameters: b 

Hone . 
Result: 

Status code (1 byte, ignore). 

Tunxtion: 

Turn on the Apple vid^o* 
Comments : 

Thia used uaed for svitcbing from the 
eo-naole video to the A.pple video^ 
Parameters : 

Hon.e« 
Results : 

Statua code (1 byte, ignoxel . 

Tujictiont 

Retumthe vidth of thia device^ 
Comments i 

This is used to determine the display 
vidth of a device^ 
Parameters: >* 

Hone • 
Results: 

Return the width of the this device (1 
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COKMAWD PESCEIPTIOH "V 
5 through Reserved 



%' 



t^ Function: ^ 

Send name ot driver. 
Comment 8 : 

This command is used to get the name of 
the driver. Since this command was 
added after the initial release of 
; ' the software, not all drivers 
support this command. To use this 
function, use the CETKAME subroutine 
in RDWRHST.ASM. 
Parameters : 

Hone . 
Results : 

Length of name (1 byte max of 15). 
Kame characters (byte length of name). 
V Error code (1 byte of 0). 



.^*.. f - f% 
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11 



.4 



COMMAND 



0/ 



# ' 



: ^^ v/ 



hexYd< 

com 


eeiaal 


tABD 


00 


■- ^- r-- \. 


01 


' : jA ': 


02 




03 




04 


. -> - . . 


05 




06 




07 




08. 


.OF 


10. 


.7F ;;: 


80. 


.83 


84. 


.87 


88. 


.8B 


8C. 


.8F ^-f^ 


90. 


.93 


94. 


.97 ^' 


98. 


.9B -'^ 


90. 


.9F 


AO. 


.A3 


A4. 


.A7 " • 


A8. 


.AB 


AC. 


.AF 


BO. 


.B3 


B4. 


. B7 ' 


B8. 


.BB 


BC. 


.BF . 


CO. 


.C3 


C4. 


.C7 


C8. 


.CB 


CC. 


.CF 


DO. 


.B3 y? 


D4. 


.D7 


D8. 


.DB 


DC. 


.DF 


XO. 


.Z3 


E4, 


.£7 


B8. 


.EB 


EC. 


.EF 


FO. 


.F3 


r4. 


.F7 


F8. 


.FB 


FC. 


.FF 



W?.^y 



^ ^^h 






PESCRIPTIOP 



Illegal does nothing 

Read data from the Apple memory 

Write data to the Apple memory 

Execute a routine 

Warm boot ri-^ ^ t^'^ 

Connect a driver 

Read 1 byte from the Apple memory 

Write 1 byte to the Apple memory 

Reserved 

Dnuced — ^-^^^ 



Block 
Block 
Block 
Block 
Block 
Block 
Block 
Block 
Block 
Block 
Block 
Block 
Block 
Block 
BlocJc 
Block 



device 
device 
device 
device 
device 
device 
device 
device 
dev ice 
device 
^device 
device 
device 
device 
device 
device 





1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 



Cha r^ c^ e r d ev i c e 
Chaxacter device 
Character device 
Cha^:act^r device 
Chaxacrer d^irice 
Char^^Ter device 
Char a c tex d e v i ce 
Chaxactex device 
Chaxaeter device 
Chaxactex device 
Chax^actex devi.ce 
Ciiaxacter device 
Character device 
Character device 
Character device 
Character device 



* I 








1 

2 

4 
5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 



«f 



,tJS.t. A4 
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CHAPTER 3/ 1/0 BTTB ^ .n^ 

This section describeo the use of the I/O byte by the 
BIOS. The I/O byte is located at address 0003b, and is 
changed either by the STAT program or directly by an 
application program. It should be noted that although 
the 1/0 byte only supports 5 different devices, the 
command structure supports 16 devices. The «^^^* 
devices arc available by directly calling the Apple I/O 
processor . ' - . - St ■ 

The following shows the relationship between the 
logical devices (CON : ,RDR : ,PUN : ,LST : ) and the physical 
device names. 

bits 7^6 5 4 3 2 10 

I LST: I PDK: 1 RDR: I COK : I 



0) 



^ COKSOLi:^ CON: • bits Jind 1. 

i • TTY: for input and output (character device ^, 

1 - CRT: for input and output (character device 3) 
I 2 - BAT: causes CRT: to be used for input and 

I output. In addition, all output is echoed to 

I 1ST:. This is equivalent to a permanent "CTRL 

3 • UCl: for input and output (character device 4) 

READER^ RDR: • tita 2 and 3* 

• TTT : as input (character device 0) 

1 - PTR: as input (character device 2) 

2 « tJRl: aa input (character device 1) 

3 • DR2: aa input (character device 4) 

PUKCB, PTJK: -- bits 4 and 3. 

• TTY: as output (character device 0) 

1 * PTP : ms oiJtpiit (character device 2) 

2 « V^lz as x>utput (character device 1) 

3 ■ STlz as output <chaxact^T device 4:) 

PRrETER, LSI^ -- ^ita 6 and 1. 

t) ^ TTT: ^OT input *nd output Icliaracter ^evic« 0) 

1 » CRT: for input mnd output (character device 3) 

2 » LPT: ft>x input and output <cliaxacter device 1) 

3 » ITLl: for input and output (ciiaracter device 4) 



$ 1- 
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CEAPTEft 4/ HAEDVAES 



4*1 APPLE 

HAKDWAEE 



The folloving chapter outlines the Apple and APPLI-CARD 
hardware. 

In the hex number, that follow, the letter "N" (such as 
OCONO) is defined as 8 plus the Apple slot number in 
which the APPLI-CAED resides. For example. OCOCOH is 
the input port of the APPLI-CAED when it is m slot 4. 



I/O PORT 
OCOKO 

OCOHl 

0C0K2 



0C0N3 



PESCEIPTIOH ; 

8 bit input port. This is 
80 writes to send a byte 
6502. 



the port the Z- 
of data to the 



8 bit output port. 
Z«-80 reads to get a 
6502. 



This is the port the 
byte of data from the 



1 bit status port. Bit 7 of this port is 
set to 1 if output data port (OCONl) is 
full; i.e., the previous data byte 
written by the 6502 has not yet been read 
by the 2-80. 

1 bit status port. Bit 7 of this port is 
set to 1 if the input data port (OCONO) is 
full; i.e., there is data for the 6502 to 
read from the Z-80. 



f^i2 



0C0H4 
0C0N5 

0C0K6 



0C0K7 



Mot used. 

Eesets the 2-80. This causes the 2-BO to 
begin execution a^ location 0. A re^d or 
wxite to this location resets the 2-80. 

Interrupt the 2-80^ This ia connected tx> 
channel 3 of the CTC on tie APPLI-CARD. 
If this channel ia BeX up properly, a rea4 
or write to this port will interrupt the 
2-80. Currentlyj. the CTC is initialized 
vith interrupts disabled. 

HMI interrupt for the 2-80, This is 
connected to the 2-80 NMl pin aiad causes 
the 2-80 to take an interrupt and begin 
execution at 66H. A read or write to this 
location causes a.n KHI. 



P^-r i , 



^^ 



% Sf % 
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Exattplc of 6502 code to communicate with the 2-80: 



RDBYTE: 




LDX 


SLOTHUM 


WAITl: 




LDA 


0C083,X 


BFL 


WAITl 


LDA 


0C080.Z 


RTS 




VRBYTE : 




TAY 




LDX 


SLOTNUM 


WAIT2: 




LDA 


0C082,X 


BKI 


WAIT2 


TYA 




" ST A 


0C081 .X 


RTS 





;GET 280 SLOTNUMBER ^ 

jGET INPUT STATUS BIT 
;VAIT FDR DATA 
;READ THE DATA %. ; 



;SAVE TRE DATA J. v 



C 



;WAIT FOR PREVIOUS DATA TO BE 
;REAI) 

;GET BYTE «"'tf 

;WRITE TEE DATA 



APPLI-CARD 
HARDWARE . 



I ■■to.-; 



i •? 



The APPLI-CARD contains the following features: 

64K of memory* 
4 MHZ or 6 KHZ 2-80. 
21C ROM. 
- . 2-80 CTC. " ^ 

\ • Apple parallel pox^ Interface circuit. 

The following is a description t>f each of the I/O ports 
in the APPLI-CARD. 



I/O POUT 



lOH 



40E 



Di:SCRIPTID? 

B hit Output port to 6502. Data written to 
thia port is buf:fered on the APPLI-CARD 
for the 6502. The data available flag at 
t)CX)N3 is aet when this port ia written by 
the 2-80. 

B tit iiiT>ut: poxt ixoxi £302^ The 650 2 data 
t>tit i« h^ull^extid on tii^ J.P:PXI-CARD and is 
re^d into the 2-BO by an input to this 
port. D^ta in this port is v^lid when the 
2-80 dat^ a-eailatl^ at bit 7 of the input 
port 40H ia aet* 



2 bit status port. Bit 7 ia the, input port 
data available flag and ia a 1 when valid 
present. Bit ia the output port 
ia a 1 vhen data has not yet 



data is 

data flag and 
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A 



I/O POTIT 
6 OH 



:i Ci M "i.-- ^^i 



80B 
81B 
82H 
83B 



DSSCRIPTIOIT 

1 bit shadow memory control output port. 
When a is written to bit 0, the ROM is 
turned off and the lower 32K EAM is 
active. When a 1 is written to bit 0, the 
ROM is turned on and the lower 32K ot k.a.- 
is inactive. The ROM is turned on at power 
up, RESET, and RESET command via ^^\^^^^;' 
interface (0C0N5). Hote that when the ROM 
is enabled, it occupies memory from 
through 07FFFH. Therefore, code which 
turns the ROM on/off must reside m the 
upper 32K of memory (8000 through OFFFF). 

' CTC CHANKEL PORT 



CTC 
CTC 
CTC 



Hote: The contro 
2IL0G and MOSTEK 



Examples of Z-80 


RDBYTE: 




IH 


40H 


RLC 




' JNC 


RDBYT-E 


IN 


20H 


RET 




WRBYTE : 


' 


I« 


AOia. • ' 


ARC 




" JC 


WRBYTE 


HOV 


A.C 


OUT 


OB 


RET 


^ -^ -> v^.^ 


s:hadow$out$ro«: 


XRA 


A 


OUT 


6 OH 


RET 


. .""■ ' . -T 


TDRlI$OM$ROMi 


KVI 


A,l 


OUT 


60H 


RET 


- 



CHANNEL 1 PORT 
CHANNEL 2 PORT 
CHANNEL 3 PORT 

1 codes for the CTC are contained in 
publications . 

code to communicate with the Apple: 



3 ;GET STATUS BIT 

s ; SHIFT STATUS BIT TO CARRY 

;JUMP IF NO DATA 

;READ TEE DATA 



;GET STATUS BIT 
^SHITT STATU-S BIT XO CARRY 
;JUMP IF OLD DATA STILL THERE 
;GET DATA FROM C 
; WRITE THH DATA 



lA - 

;TURH OFF ROM 



;A - 1 

;TURN ON ROM 



V^ 



ft 
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A^ 



APPLI-CARD After pDwer up or a. 2-80 reset (0C0K5), the ROM on the 

FIRMWARE APPLI-CARD gains control. At such tine, the 2-80 writes 

— an ASCII 2 (05AH) to the 6502 input port at OCOKO. The 

first thing an Apple progrsn must do is read this data 

from the OCOHO port. After that, the following four 

conmands may be used to control the APFLI-CAR.D. 

■ote: all 2 byte parameters are sent low byte followed 
by high byte* 

COKMAIfP DESCEIPTIOH ^^ 

© FuDCtioii: 

Return the ID string ••280'\ROM VER, 
SERIAL NUMBER. 

Faraxneters: .j't^s- • .r - • . _ 

None • 

ReBul ts : 

••Z80" (3 bytes ~ 5AH , 3 8H .30H) . 
rj^ ROM VERSION (1 BYTX binary value) • 

SERIAL NUMBER (4 BYTES binary value, low 

'' ^--^■:^-:--- .:- ^tn- .. r >tf,.. ^ ^yte first). ,^^^,. ,^.,,,. ...,_. _^ . .. 

1 Function: 

■TiqA 4- - : rs Read data from the A^PLI-CARD aexiory. --"> 

FaraxDeters: i , 

Starting address (2 bytes). V^ 

,4 Number of bytea ( 2 by te^ ) . 

■^ -'^^ " Results^ 

Data returned (number oi l>ytes). 

% Function : 

Write data to the APPLI-CARD memory. 
Farametera : 
. : ¥5 Starting addresa (2 bytea)* 
I Avi 31 ;. :" Number of ^ytes il l?ytes)^ 
^? v! rii : ^_ Z Data bytes (number oi byXes)^ 

■ . _ ' . /^' 't ' . '^ ;•"- - : ' ' * 

: 3 i I .. .; / Functions 

Call a prt)gx^m. 
Farametera: 

Starting ad4reas i:2 byt«-s). 
Reawlta^ 
r^' i> ^- Hone* • i :- : ---f?- 

Vote: In version S*0 of th^ APPXI-CARD, 
the following commands have been adiled: 

A -:i«: .|. Tunction: ^:^ll . -j^*^.-- ■ 

"Write x)ne byte to AFPLl-CARD I/O port. 
Parameters: _ 

1/0 port address (1 byte). ^ 

Byte to output (1 byte). ^^^^ 

. Results z 



^** A 
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COMMAHD DgSCEIPTIOW ;>/., 

5 Function: _^ , /« ► 

Read one byte from APPLI-CARD 1/0 port. ^^ 

Parameters : 

1/0 port address (1 byte). 

Results : 

Data byte read (1 byte). 

While the firmware is running (i.e. the shadow ROM is 
on), the Z-80 will wait for approximately two minutes 
for the first command or between subsequent connands 
from the Apple. If no command is received during that 
time, the Z-80 will cease looking for commands and 
start diagnostic testing. At this time, it will write 
a binary to the Apple data port (output port 0) and 
increment this value approximately four times a second. 
The continual incrementing of this value indicates the 
diagnostics are running properly. The diagnostic 
program may be interrupted and communications with the 
Apple restored by resetting the APPLI-CARD (access ti 
0C0N5). . . • :; 



i b^ ■ 



\^' 



1 . 



\^: 



'Km 
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CEAPTEE 5/ DEBOGGIHC DEIVEtS ■-'i.i^^^^^^^^ 

INTRODUCTION Debugging drivers with the APPLI-CARD i. complicated by 

the real ti»e communication between the two coaputerB, 
and the fact there is one only debugging conEole and 
one communications port for the two machines. 

At stated in the source code, never attempt to trace 

' '' through a routine which communicates with the Apple 

"•' ' ■ from a 2-80 debugger. Since both the debugger and your 

'"'-■ :" code will be trying to talk with the Apple at the same 

" time, the system will invariably hang. The only way to 

debug communication problems is to do it from the Apple 

- ^ - side . 

The first thing you must be able to do is set a break 

' point in a driver. To set a break point, you oeed to 

get to the Apple monitor. If you have an INTEGER BASIC 

' Apple, then all you have to do is press reset. If you 
do net have an INTEGER BASIC Apple, you will °eed to 
patch the command processor program while the APPLI- 
CARD is booting (see RESET PATCH below). Any tiae the 
APPLI-CARD is waiting for a character to t>e typed, you 
may press reset, writ* a character to OCOHl (the 6502 
output port), a-nd then reenter the command processor at 
0B038E. 

The following example assumes that the APPLI-CARD is in 
«lot 5. Be certaiJi to change the I/O addresses if 
APPLI-CARD is in a different slot. 

A> .._ {PRESS APPLE RESET WHEN TSE PilOMPT IS 

DISPLAYED} 

* {SET ANY BR.EAR POINTS} 

*C0D1:A1 {SDPPXIf AN "A" AS TEE CEARACTE^R TYPED) 

♦B03BG {REENTER TEE COMMAND LODP;) 

' * ' A>A {WE ARE NOW BACK INTO CP/M WITH THE "A""} 

It is necessary to know where y©ur code is loaded. The 
drive code i« loaded sequentially beginning at OBODE- 
SPTVIDEO.DVR ends at 3600E, and EIRESIO.DVR ends at 
7000E. Begin looking for your code 'after these points. 
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#.2 RESET 
PATCH 



If you do not have an INTEGER BASIC machine, you may 
patch the Apple command processor loop at 0B22FH with 
65H, and 0B230H with OFFH, To perform this patch , hit 
reset after the screen has cleared and before the 

Then patch the above 
>y executing at OBOOOH. 



reset after the screen has cle 
LOADING DRIVERS message appears, 
locations and continue the boot b^ 



'^ «, 



'^ %^ 2 * 5 



' -^^-i . 



^- ^ '"r %. '. 






.7 4 



^ A =** ^ t 






^■IAW^. -*'■- ' 
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CHAPTER 6/ ASSEMBLBH 



' %'^ 



INTRODUCTION 



The 6502 Ctobb Asueoblcr A65 wee designed to tranclate 
6502 assembly source files to a relocatable fornat. It 
ruDS under CP/M on the AfPLI-CARD and uses CP/M i^^^^* 
The output of the assembler is linked vitb other 
modules to form an object file* It is not necessary to 
use this assembler and linker, of course, but they are 
provided if you wish to use them. The sample files use 
this assembler. 



USER 
INTERFACE 



To execute the assembler, the following files must be 
present on the default drive: A65.COM, hAIN65.0YL, 
DMPTABLE.OVL and OPCDE6 5.TXT,. Type A65 and follow 
the prompts noted below: 



A>A65 

Input file name : 
Output file name 
List file nam e 



BiCDEXllPL 

: BrCDEXllPLO 
(cr or NONE: 



for none): BOEE 



The input 
name. If 
assumed • 



source file name is a standard CP/H file 
an extent is not present, then .A65 is 



Examples of input file names 



SVA2TX4 

B:SVA2VX4 

C:SVA2VX4.ABC 



{SVA2VX4.A65 on 
{SVA2VX4.A65 on 
{SVA2VX4.ABC on 



default disk7 
drive B} 
drive C} 



The otitput file name is the file to which the 
relocatable output is written. If a dollar sign ($) is 
us^d in place of an output file, then the name of tii e 
output file is the same as the input file name^ except 
with an extent of ^ERL^ If no extent is provided, tlien 
.XRX is supplied. 



Examples of output file aames 



CDEXMPL 
B-.CI)EXKPX.X)UI 



{Sam^ f il« 4iame as input but .ERL} 
{CDEXllPL.ERL on defaixlt drive} 
{CDEXMPL. OUT on drive B} 



The list file name is the file to vhich the listing is 
written. If a dollar sign ($) is used in place of s 
list file, then the name of the list file is the same 
as the input file name^ except with an extent of .PRH- 
If you do not want a listing f ilej then enter a return 
or HOKE:. Other legal names are LST: for the 
and CON: for the console^ 



printer » 
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Examples of listing file n&mes: 



BDEXMPL 

G:BDEXMPL.LST 

LST: 

CON: 

HONE: 



{Same file name as input but .PRN) 
{BDEXMPL. PRN on default drive) 
{BDEXMPL. LST on drive C) ^ 
{listing to printer) 
{listing to console) 
{No listing) 



6.3 SOURCE 
SYNTAX 



Source files consist of lines of AS CIl cba r a c t er s 
terminated with a carriage return and line feed. The^ 
format of each line is: 

; * -- label opcode operand ;comment 
vbere any or all of the fields are optional. 



6.3.1 LABELS 



The label field is a string of characters which begin 
in column 1, and start with an alphabetic character 
('(?', 'A" to 'Z' or dollar sign '$') , followed by any 
number of alphanumeric characters. Only the first 8 
characters are isignif icant . Xf the label begins with a 
dollar sign, it is a temporary label which is active 
between two non-temporary labels. 



6.3.2 OPCODE 



The opcode field may be one of 
6502 opcodes or a pseudo opcode. 



the HOS Technology 



6.3.3 OPERAND 



The operand field is optional or mandatory depending on 
the opcode. Expressions in the operand field may be of 
two types: either numerics or strings. String 
cxpressionB are multiple character atringa imbedded 
between two double quotes. Exajnples; 



• BYTE 
.BYTE 



'•THIS IS A STRIl^G^ 
^AB*' 



;A SHORT STRING 



Numeric expressions may conais^ of numbers, a aingle 
cl^aracter in double quotes, or a label with optional 
operatora and par entlie s is. Operators of the same 
precedence are evaluated left to right. The following 
are t.he operators in order of their precedence: 
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PRBC. OrERATOR 



1) 
2) 

3) 



s # i '*' ;,. 



,«i t^ ^ 



A) 



4 ^, 



5) 



/ ;i -^ 



{) 



HOT 



t 

11/ 

HI 



AND 
£0£ 



<> 

>^ - 

<« 

U- 
D<> 

U> 
V< 



Pmr en theses I 

Unary operators ;^ 

positive 

negative (twos cotapl imen t ) 

bit^vise oncB conpliment 

Multiplicative operators 
signed multiplication -^ 
signed diviB ion ?- - 

signed taodulo (renainder) 
unsigned xnul t ip 1 ica t ion 
unsigned division 
unsigned modulo 

Additive binary operators 
add 

subtract * v^ /^: lj 

uns igned add 

unsigned subtract 

bit-vi se and 

bit-vise exclusive-or 

Comparisons ..^^i^.:: 

equal 

not etjual 

greater than ■.:• ^n;- ^t- : 

less than 

greater than or equal 

less than or equal 

:u n s i g n e d e q-u a 1 cl -;. k.2, : ^^ / 

unsigned not equal 

unsigned great ex than 

unsigned less than 

unsigned ^reat^r than or 

equal to 
unsigned less titan or equal to 



K^ 



.A KU-HEHIC 
COlx'STAKTS 



Kumeric constants in expressions nzy be one of four 
radices: bitiary^ octal, decxjnal ox liexa^iec ima 1 » vitb 
the radix as a suffix to the constant, l^hen no radix is 
specified, the default radix, ^ecimal^ is used* The 
folloifiii^ are examples of each type^ 



256« ;decimal the default 

lOOB jhex 256. 

lOOB jbinary 4. 

lOOQ ;octal 64. 



V^ 
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6.4 PSEUDO Below is a list of pscudo ops for the assembler. 

OPERATION Bote: Braced items are optional. 

.BLOCK expression ^ 

* Reserves expression number of bytes in the 

program. .^ i^ ,., , 

•BYTE expression{ , expression} 

Defines bytes and strings in a program. 

.BEF name {, name} 

^^ ^ Defines a list of labels as entry points 

into this module. Each name in the list 
must correspond to a label and not an 

X .^t- ' ^s^ equate. There may be any number of .DEF 

:.rr^-% ■^- ■•: -fe . statements. 

.DSECT 

-fta> ^^. Tells the assembler to assemble all of the 

ft -* i generated code into the data segment. 

Tjas a ■. T normally this segment is used for data 

b - ; ^ .# ir ?;^ - areas. At link time, the address of 

A . .DSECT is set with the J l> switch, or 

^ tfa: A ^ defaulted to the area following e^ch 

1^ module if no /D is used. 

•EQU expression 

Defines a label with a specific 



value . 



•IF expression 
{.ELSE} 



.ENDC 



\ ^ ^ 



be nt^ 8 ted. 

.INCLUDE file name 



.IFj .ELSE, and .ENDC are used for 
conditional assembly.^ If the expression 
evaluates to something other tii^n 0, then 
the code following the .IF ia assembled. 
If tJxe expression evaluates to 0^ antl i±^ 
mn .ELSE i« present, then the cod^ 
assembled Is the code between the .ELSX 
and tie matching .ENDC. IF statements may 



CtLuses the source code from the specified 
diskette file to he included in the main 
.^ source code (as if it were written 

xnlme J • 

»LINES expression . «.^. 

^%i Defines the number of lines per page. 
Default ia 66. 
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► LIST 



^*- 



.NOLIST 



" .tft ^ 



Directs the asEemblcd code to the liBting 
file. 

DiscontiBueB output of the asaembled code 
to the lifiting file. 

•NAME "string" 

Defines the module name for the linker 
f *^^ ^ i (may be up to seven characters long). 

Z : ^ .PAGE {"string"} 

" Advances to the top ot the next page and 

allovs a subtitle as an option. 

.PSECT ^^- ■ ..«....--.^. ^.^. -^ 

^ i ^ Tells the assembler to assemble the code 

^ - ' "^ * ^ ^ ^ ^^ tf ^ into the program segment. This is the 

^ ^- - s : V I ; < . default if neither .DSECT or .PSECT is 

- ^r : t ,^ invoked. Normally this is the segment used 

'^ - / for executable code. .At link time the 

1 - - - « "* ^ -Address for .PSECT is set vith the /P 

switch or defaulted to lOOE if no /P is 
tised« 

- ^QUZ^Y "atring" 

Queries the operator for input after 
displaying the atring. This accepts the 
operator's input and assigns the value in 
exactly the same manner as .EQU. 

' ' *REF name {, name} 

Specifies a list of labels vhich are 

- ' ■" defined in another module aa .DET^s and 

' * * j^' ^* V h i c h a r e to be accessed by this m o d 4j 1 e • 

' '- ^^^ - Kote: cixxrentlj no arithmetic is allowed 

^-"'^^ on .REF labela (the assembler tloes nxt 

^' ' "'^ -^ / ' ; generate an ^rxDr). 

• TITLE "string*' ^5 ^ ^ 

String ia printisd at tte top x>t e^ery 

^ " - ^^^. -^ ^- ' -^ -' / .%tlJ)TE expT^aaion 

'^^* ^3 Defines tixe width of the outputs Default 

ia 79^ 

' •WORD express ion < ^expression} i^r^ j 

'^ ^ Defines vorda in LOW byte BIGE byte order. 



m 



^ 



ASSEMBLER 



•5 BUGS IN At the present time, the afsembler has several bugs 

THE which are described below. * 

1) When a label defined in a .REF list in used in an 
arithmetic expression, an error occurs. Currently, the 
assembler does not flag this error and the linker does 
not relocate it properly. If you need to do 
calculations they must be done at runtime. Typically 
this condition arises when a 2 byte variable needs to 

^ be accessed. You must either define 2 labels or use 
indexed addressing to access the other byte such as: 

.REF LOLBLl , HILBLl t? ji 

LDA LOLBLl ;GET LOW BYTE 

LDY EILBLl ;GET HIGH BYTE ! .4 -^ 

or 

LDX #1 1 . . . . 

LDA LOLBLl, X ;GET BlCa BYTE * = -r 

TAY ^ ; TO Y - .: 

LDA LOLBLl - I > ? jGET LOW BYTE TO A 

2) Too many local labels cause the assembler to die. 
This is the only known bug that causes the assembler to 
stop while assembling code. Xf the assembler does stop 
for no apparent reason, try changing some of the local 
labels to global labels. This happens only on large 
files . ■' r~ - .t - . - f 

?^ 3) The assembler also dies wlxile printing out a large 
symbol table. This also occurs only on large files* 
^ The user may ignore it, or bre^k the file iuto smaller 
■ ' modules^ 

4) The assembler genera-tes an error when, ioing ^n 
^ expression^ such aa: 

^ CXXHST .EQU 3 

- f LDA LABITL+CONST + l 

XABELi ^ MOT ^ 

solution: 

COKSTl .EQU 3+1 

LDA LABELi-COHSTl 
" LABEL: 



'^'^^ 



%^d 



CEAPTEH 7/ LIHtKR 



The linker is used to convert the output of the 
assembler into an object file. The linker can ^1*^/^ 
used to combine or link several separately assemblea 
modules into a single file, and resolve the references 
betveen them. These references are defined by .vZI s 
. ^^^ -^ and .REF's in the assembly language source filee. 

USER To use the linker, you must have the two files, 

INTERFACE LIKR.COM and LINR.OVL on the default drive. The linker 

is invoked by typing A>LIKK. The input string for the 
linker is defined as follows: /;.:t^.^o:^a ^'fi.- 

{output file->input filel, input file2, ... input fileN 
{switches } 

The output file is optional. If not present, the 

output file will be the same as the first input file, 
except with an extent of .COM. Only the first input 
file needs an extents If not present, the default 
extent, .ERX, is used. Switches are used to coctrol 
actix>ns by t±e lijnker. Each of the switches is preceded 
by a slash^ (/)» followed by a letter, and 
' -^ 'S ts (optionally), a parameter. ... ,^^_ -. 

.*^^ ^ ^■-- XXHKER T.:^^ OPTIOK SVITCBES ^^ t Iv - t^ h .->^^ ^ 

,v ^ ^ - IJL ; /A causes the linker xo abort opexation 

without any processing. 5 „ 

^^ |C^^ : Jt aisBB-l* the linker that more input 

^ ^ . files axe found on the nex:t line. Tbis is 

e .. ua^d when more input filea are used than 

ean fit 04a one line. Tie last line has no 

/C. 

/D:valu.e /T> aeta 1>ejinniiig address of the data 

segments ^DSXCT. The value parameter is a 
hexadecimal numb:ex* If /D is not used, the 
default ia the data follows the co4e of 
^aoh module^ There may ouly be one /B 
switch. 

/I Jz causes the Ixnkex to output symbols of 

.REF's and .DEF'a which begin with an ^'g"* 
Symbols which begin with a *¥" may be used 
in system library modules, and are not 
normally used in a program* Thi« 
eliminates some possibilities of multiply 
defined symbols* 
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/L /L causes the linker to output the program 

and data area location* for each nodule. 

/M /M causes the linker to output the symbol 

table of the .REF's and .DEF'a. 

/N /N causes the linker to refrain fron 

writing the data area to the output fxle. 

Space on the disk is saved if the data 

'area does not contain any initialized 

.. . data. , ,„, „,.^ ..-.-*.< ■ 

/p /F causes the linker to assume that the 

file name preceding this switch is a file 
which contains linker input commands. 
This can be used instead of a submit file. 
.CMD is assumed if the file does not have 
an extent. 

/Prvaluc /P sets the address of the program segment 

.PSECT. The value parameter is a 
hexadecimal number. If /P is not used, 
then the default is lOOH. There may only 
be one /P switch. 

/S /S signals the linker to search the file 

associated with this switch and uses it only if there 
is a reference to it which is currently undefined. This 
feature is used mainly with libraries and system 
modules so unnecessary routines will not be loaded. 

/X /X allows this linker to assemble a 68000 

file. It should not be ^xsed. 

Examples of using the linker: 

Link CDEXMPL.E^L at lOOH. The outp^4it file will be 
CDEXMPL.COM. 

A>L11IX CBEXMPL 

Link BDEXMPL^ERL at 0. The the x>iitpttt file will be 
BDEXMPL0.COM. 

A>LIXIX BDEXMPLO-BDEXMPL/PxO 

Link TEST.REL at 7000H with the data area to 300E, and 
shotr the complete symbol table. The output file will 
be TEST. OBJ on drive A:. Kote that TEST.REL will be 
on drive B:. 

A>LIDX TEST.OBJ-B:TEST.EBL^LIBRAXLY/P:7000/D:800/L/M/f' 
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' — \ 



■ff 3.: 



Liok TESTl through 10. ■ 

A>LinK TEST1,TEST2, TESTS', TEST4/C „*; 

*TEST5,TEST6/C 

*TEST7 .TESTS ,TEST9 ,TBST10 

Link TESTl through 10 with a .CMD file. TEST.CKD looks 
like this: 

TESTl ,TEST2,TEST3 .TESTA, TESTS /C 
TEST6,TEST7 .TESTS , TEST9 , TESTl 0/P : 5000 
/D:100/L/M/E , ,^ 

A>LinK TEST.CMD/r 



BUGS IN 
TEE LIKKER 



The only known bug in the linker is that the output 
file tends to be one sector larger than necessary. This 
can cause probleas when concatenating files for a 
DRIVER. The solution is to rely en the size of the 
module defined in the aesemblex And not by the size 
the file output by the linker. 



of 



'\y 



^ -> r 



'Sf §-- 4 ^t 



5 !? -■* m^^i 
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CHAPTER 8/ GEHHAP 



-, i^.'^A -^' 



Z.l USER 

INTERFACE 



^. ,^ ^ 



Thi« file generates a bit map by comparing two input 
files and outputting the bitmap. 

The user supplies two input files on the command line. 
A single file name (using the name of the first file) 
is created with an extent of .MAP. 

Example : ' -- ■ -■ 

A>CEBBMAP FILB1.COM FILE2.COM 

The output will be FILEl.MAP 



e.2 BUGS IN 

THE GENMAP 



As in the linker, GENMAP tends to output 

a file one sector too large. The actual number of valid 
bytes is the length defined in the assembler divided by 
8. 



S « « i t 



APPT.T — CApn nVM wrfiwrt$r /T»*r»w ^n 



r~' 



CEAFTEE 9/ OTHKE FILES 

The other files supplied on the OEM disks are er.plained 
be low. 



BDEXMPL.A65 



CDEXMPL.A65 



APLFLPY.A65 



SVA2VX4.A65 



DEVREQUS.A65 



This is an example of a block device 
driver and is to be used as a skeleton 
block device driver. 

This is an example of a character device 
driver and is to be used an a skeleton 
character device driver. 

This is a block device driver vhicb makes 
EVTS located at BDOOE to interfiles vith 
the APPLl-CAED* Thia is an example of a 
complete driver. 



This is also an example of a block device 
driver and shows how multiple 4ensity 
devices are aupported. 



This is an inolude file usetl by the above 
rt>utines. It i^icludea system equates. 



RDVEH5T.ASK : 

Thia is a file which cam b« lised by a 2-SO 
program to talk ^iirsctly wixh the BOST 
650 2. 

RVHEXKPL^ASH 

This ia an exam:ple of a program which usea 
ED^HHST.ASii* Thia program searches for a 
4ri"ver of a particular name and then moves 
tlie liead of the driver off the ^ata ^rea. 



1!**SD3 



The files which l>egin with M and have and 
extent of ^U£ are submit filea ^hich 
l>nild a dri^ex* 
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TECH STJPPOET NOTE 

"^ — ^ BE: Appll-card driver memory usage. 

Note: These memory addresses are In tlie Apple's memory. 

Tlie 6502 control program (CP6502) begins at BOOOH. Tills code Is 
approximately 700H bytes long. The drivers which have been 
Installed In the DEIVERS file are loaded sequentially, following 
CP6502. SFTYIDEO Is always the first driver. and It Is about 
18B0H bytes long. ^^., ,-,— ^.^ ^^ ^ _ .. . 

If using the HIBESIO driver, It will be loaded at 6000H; this 
code Is lOOOH long. so It ends at 7000H. This driver uses the 
Apple hires pages at 2000H and 4000H. 

There are device tables beginlng at 8E80H, so this area must not 
be affected. 

Addresses 9000H to APFFH contain a copy of the CP/M Image, which 
Is used on a reset (warm boot), rather than going to disk to get 
the image on a warm boot. 






* Note: Locations given in the OEM manual on pg. 19 for beginning 
^"-^ of drive code and SFTVIDEO location are in error. 



'^llT^. .-* ? 



>^ 



* x^ 



, - -1 -^ 
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APPLI-CARD BOOTSTRAP PROCESS 

The bootstrap process for the APPLI-GARD on the Apple II, II 
lie is initiated by a 256-byte bootstrap written in 6502 
residing in the first sector of track on. the boot disk, 
bootstrap is part of the file PGPICPM which is written to 
system tracks by the INSTALL utility program. The PCPICPH 
is structured as follows: , r - .., . 

0000 - OOFF Apple bootstrap (6502 code) - ^ ' "^ 

0100 - 1FFF GP/M (CGP, BDOS and BIOS - Z80 code) ^ ' * 

2000 - 27FF GP6502 (6502 I/O control program) 

2800 - ?FFF RWTS (6502 floppy disk I/O code) ' 

The Apple bootstrap reads the remainder of the PGPICPM file, 
containing GP/M, BIOS, GP6502 and RWTS, starting from sector 1 of 
track into contiguous memory locations in the Apple beginning 
at address 9100 hexadecimal. The bootstrap then transfers con- 
trol to the initialization entry point of the GP6502 module at 
3000 hexadecimal. ^ 

During the -second phase of bootstrapping, the CP6502 initialisa- 
tion code creates the various tables it requires for later opera- 
tion, locates the 280 APPLI-GARD I/O slot, passes the GP/M and 
BIOS code up to the Z80, and then enters its normal waiting loop, 
-ready to respond to commands from the 280* 

The third phase of bootstrapping is handled by the 280 GP/M BIOS, 
which is part of the code uploaded by the GP6502 modxile in -the 
Apple. The BIOS cold start routines initialize the 280, I/O 
ports and interrupts, then call GP6502 to load tbe DRIVERS file 
into the 280 and connect individual drivers t.o specific devices 
in the Apple. After device drivers are ioaded and connected, the 
BIOS displays the sign-on message, loads and executes the 
mutostart file (if any), and transfers control to GP/H^ 



BOOTING FROM OTHER THAN APPLE FLOPPY DISKS 

Booting the APPLI-GARD GP/M system from disks other than the 
default Appl« 5.25" floppy disks requires that several sections 
of executable code and default table information be examined and 
possibly altered to be compatible with the new bootstrap disk 
type^ The ar^as which must be exaiained are: 



1. 
2. 

3. 



Boot disk parameter block data (part of GP6502) 
Default disk driver (psirt of CP6502) 
Bootstrap loader (OOOH • OFFH in PGPICPM) 



The Apple I/O control program, GP6502, consists of three 
components, 1) the main control program. device driver 
communication and initialization routines, 2) a default disk 
driver used during the remainder of the bootstrap process, 
and 3) a default console driver. In some cases, the new boot 



w 

-'-% 



disk will be software compatible with standard Apple floppies and 
different only in density or total capacity. In these instances, 
the bootstrap sector and default disk driver need not change, and 
only the disk parameter tables in CP6502 must change. At 
CP6502+05FH are the following disk parameter tables: 

HOST PARAMETER TABLE 
Bytes per sector 
CP/M records per track 
CP/M records per host block 
CP/M records per allocation block 
Sector mask ,,,-,, 

Sector shift count 

DISK PARAMETER BLOCK 
Sectors per track 

Block sl^ift factor ., , ^ ' ? .-? 
Block mask 
■ Extent mask 

Blocks on disk - 1 

Directory entries - 1 - ..>..; "^^ 

AllocO 

Alloci '■ ' . i 

Check masks v^ 

Directory track offset i 

If the new boot disk is .not software compatible with Apple 
floppies, both the bootstrap and the default disk driver in 
CP6502 must be changed (which generally means replacement). Two 
tables residing in the main CP6502 module contain pointers to the 
four entry points of each of the defaiilt drivers. The block 
driver table is located at CP6502+0^AH and the character driver 
table Is immediately following at CP6502+052H. The four words of 
the default disk driver table must be changed to point to the new 
disk driver's UflT, READ, WRITE and OTHER entry points. 

Generally the default character driver is loaded at an address 
lower than the disk driver, so tha^ a new default di^ driver may 
be loaded directly over the existing driver. The new driver may 
™« ^®^ "^^^^ ^'^^ ofiginar, provided it does Jiot extend into 
RWTS, located at CP6502+800H, If the new CP/M configuration will 
never need to- use EWTS, tbat is, never use AFT Apple floppy 
driver, then tlie -new disk driver may extend into -the space reser- 
ved for JIWTS. 
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Tlie PCPI APPLI-CAHD can liave up to two Appll-BlBC EAM 
extender cards instfiiled to provide up to 256K bytes of EAM 
memory in addition to tlie 64K bytes on tlie Appli-Card. The 
additional memory on eacli EAM extender is viewed as eith.er one or 
two banks of 64K bytes each.. 

"*-■ 
I. SOFTWABE ADDEESSING - — T ^"^^ ^ 

EAM banks in an Appli-Card witb EAM extenderCs) installed 
are numbered as follows: 

: BANK £ — -%.. ■.- ■ ---"^^-^ sa 'f;.lw-lf 

« .. APPLI-CAED main 64K memory v" fj..: ^ 

2 « 1st 64K bank (EAM extender 1. bank 1) f'^ :' 

4 « 2nd ^ f ( - t» 1. « 2) -- ) 

6 « Srd •• " ( *' " 2. ^ 1) 

8 «= 4tli •' " , ( " " 2, •' 2) 

EAM banks are selected by writing a byte witb a 280 "OITT" ^O" 
instruction to port OCOH. 

Bits: 



4. and O are ignored. 

Bit 6 controls an 8 or 16K byte common area^ 

«= 1 disables coinaoji EAM and enables tlie entire 64K in 

tbe selected bank. 
« O enables a x:ommon bank 'cf el tlie r* 8K or 16E on tbe 
APPLI-CAED, depending upon jumpeT position^ 
disablin^g tlie corresponding addresses on tbe EAM 
extender card, Tlie BK common area resides at 
addresses EOOOH-FFFFH; tbe 16S bank is at COOOH-PFFFE. 




/^ZJ^ ; ^7^./ rV^- ^r/.^cy(^^< 



^^^r ^ 



*f^e 






II. HABDWAEE JUMPEES 

EAM extender boards contain several plug-Jumper locations 
wlxicli are used to assign banlc addresses and common bank 
configuration for each board. Near tlie upper left corner of 
each, HAH extender board tbe following jumpers and labels can 
be found: [•'o'' Indicates a pin, ^ •• is a jiimper] 

COMM. o o o 

., . SIZE ^^-^_ ^,^A---:-n-tAt ^^^- -.^ ^ ^^'T *^ ^^.is^: m. > .^^^c^ 

Tlie jumper cbolce for 8K or IBK common area size Is 
normally on the 8E side. Tlie common area Is tliat area 
of memory retained from tlie Appli-card*s bank of 64K 
to eacli 64K bank of extended memory. Tbe common area 
* / Is tbe blgh 8K (orl6K) address locations, wlilcli will 
contain an image of tlie CP/M operating system. 

1ST 2ND 

BD. o-— -o o BD. .'.-^^ ' - . -^i^ 



o o o 

o o o 






■# 



Tbe 3 jumper plugs should be installed as shown above 
(covering left & middle pins) for the first extender 
board. If a second extender board is present, the 3 
jumper plugs for the second board should be installed 
in the right-hand position (cov^eTin.g right & m^iddle 
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TECH SUPPOET NOTE 

HE: APPLI-CAED lOBYTE alteration notes - ^ - :^^-^^^ 
DATE: Summer '84, P^B, '^^ - ^"^ 

The Appli-card's lOBYTE default setting can be reconfigured In 
version 1.5 and later. Also, the prototype arrays for defining 
the corresponding character devices for each physical device 
setting can be altered In all versions. ^^^ -^ 

At times It is desired to put a printer interface card in a slot 
not currently supported by CP/M for printer output. The details 
here will aid in modifying the APPLI-CAED CP/M so that the LST: 
will support printer output to an interface card in a slot other 
than those supported (slots 1 and 4)'. 

The 4 assignments the LST: (printer) can have are TTY: , CET: , 
LPT:, and ULl:. Eespectlvely , these have character device values 
of 0,S,1,4 (which correspond to slot numbers in the Apple). 

The lOBYTE default is for the LST: to «= LPT: , therefore the 
printer interface card would normally be in slot 1. You could, 
for instance^ put a printer card in slot 4 and use the STAT 
command to reassign the LST: device (i.e. STAT LST:«=IJL1: ). • 

Since slots 2, 5, or 7 aren't assigned to one of the device 
names^ it would be necessary to patch PCPICPM to enable use of a 
printer card in one of these slots. 

The APPLI-CAED IDBYTE default setting can.be reconfigured in 
Terslon l.S a,nd lateT. Also, the prototype arrays, which define 
the ^har. device (slot #) for each physical device, can be 
altered in all versions. 

First load PCPICPM into memory using DDT : A>DDT PCPICPM 

The memory addresses given below assume PCPICPM is loaded at 

address IDOH^ which is where DDT loads it. 

*** TEESIOH 1.0 **« 

The lOBYTE default (at location 1866E) cannot be changed in this 

vexislon^ loid will be initialized at 9SH. 

The prototype -arrays (each being 4 bytes long) are located as 
follows: 

COK: 1D65 thru 1D66 

LST: 1D71 thru 1D74 

^ EDE:^PUK: 1D7P thru 1D82 

*»• VEESION l.S, l.SA, 1.6, 1.6A *»» 

The IDBYTE default is located at 184D, and is set to 95H. 

The 4 byte prototype arrays follow consecutively in this order: 

CON: 184E thru 1851 

I-ST: 1852 thru 1855 

EDE:,Pira: 1856 thru 1859 



»«* TEESION 2.0 ■•» 

Tlie lOEYTE default is located at 1B5F, and is set to Q5H. 

The 4 byte prototype arrays follow consecutively in this order; 
CON: .^ 1861 thru 1864 

LST: ' 1865 thru 1868 : \ 

EDEx.PUK: 1869 thru 186c ' : 



»«« Format of the lOBTTE *■• 

The lOBYTE itself shows the relationship between the logical 
devices (COH: ,BDH: ,FI7II: ,LST: ) and the physical device names. This 
byte (8 hits) is broken down as follows: 



bits / 7 6/5 4/3 2/1 

/ LST: / PUN: / EDE: / CON: 



f ,/ 






CON: 



EDE: 



bits 

1 
2 
3 

bits 

1 
2 
S 



and 1 

■ TTY: 

- GET: 
» BAT: 

- UCl: 

2 and 3 

■ TTY: 
» PTE: 

- TJEl: 
= ■DE2: 



(char, device 0) 



( " 
( " 



(char. 
( " 
( " 
( " 



3) 

3, and o-atput to LST:) 

1 or 2 depending on version) 



device 0) 
2) 
1) 
4) 



PUK: 



bits 

1 
2 
3 



4 and 5 

» TTY: 

= PTr: 

« TJPl: 

■ irp2: 



(char, device 0) 

( " "2) 

( " " 1) 

( " " 4) 



LST: » bits 6 and 7 

= TTY: 

1 -= GET: 
-2 « LPT: 
3 « m.1: 



(char, device 0) 

( " " 3) 

( " " 1) 

( " " 4) 



The middle 4 bits (bits 2—5) in a prototype byte ar« tlifi ones 
which, establish what the Character Device Number will be. 
Bits and 1 have valiieB ol 0. Bits 6 and 7 have values of 1. 



Por example! the prototype byte for LPT: is set for char, device 
#1, This byte would look liie this- 110 00100 
which equals a hex value of 04. 

To change LPT: to be set to char, device # 7. The byte would look 
like this: 11011100 which equals a hex value of DC. 



/ 



Tot your information, all values would be: 





Bits 


Hex 




10 


CO 




10 10 


04 




10 10 


08 




10 110 


cc 




10 10 


DO 




10 10 10 


D4 




10 110 


DB 




10 1110 


DC 



\ 



Using DDTt patcli in this new hex value at tlie correct 
as noted above by version number* 

Once you bave patched PCPICPM, tben you must run 
program so that tbis is rewritten on the boot tracks. 



Cbar dev # 
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^.:;it:r;i\ 
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correct 


Location 


run tbe 


INSTALL 
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